<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
            "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
	<title>Layout - Screenbar Documentation</title>
	<link rel="stylesheet" type="text/css" media="screen" href="style.css">
</head>
<body>

<H1>Layout</H1>

<H2>Overview</H2>
<a name="overview"/>

<P>The layout of Screenbar panels is defined by a hierarchy of widgets, each of
which is identified by a string which is also the prefix of all its options.
Every element must have a type, given as (prefix)Type; this defines what the
element does and looks like and what other options are available, and it is an
error to use an element without defining its type. The following options are
available for all elements, regardless of type:</P>

<H2>Element Types</H2>
<a name="types"/>

<P>The element types are</P>

<ul id="namelist">
	<li id="namelistitem">
		<div id="itemname"><a href="branch.html">branch</a></div>
		<div id="itemdesc">
			One of several children depending on a boolean expression
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="flow.html">flow</a></div>
		<div id="itemdesc">
			A series of elements arranged in sequence, optionally with copies
			for each desk or each task within a desk
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="group.html">group</a></div>
		<div id="itemdesc">
			A set of elements named in (prefix)Elements drawn on top of
			eachother.
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="icon.html">icon</a></div>
		<div id="itemdesc">
			The icon that belongs to the context task.
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="label.html">label</a></div>
		<div id="itemdesc">
			A text label with either a fixed string, the context desk's number,
			or the context task's window title.
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="minimap.html">minimap</a></div>
		<div id="itemdesc">
			A minimap of the context desk with all its windows.
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="childmodules.html">module</a></div>
		<div id="itemdesc">
			A child module
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname">null</div>
		<div id="itemdesc">
			An empty placeholder for an element
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="snapshot.html">snapshot</a></div>
		<div id="itemdesc">
			A scaled screenshot of the window(s) of the context task
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="startbutton.html">start</a></div>
		<div id="itemdesc">
			A start button
		</div>
	</li>

	<li id="namelistitem">
		<div id="itemname"><a href="texture.html">texture</a></div>
		<div id="itemdesc">
			A button or decoration with an image or draw effect
		</div>
	</li>
</ul>

<H2>Positioning</H2>
<a name="positioning"/>

<P>Flow, icon, minimap, module, start, and texture elements take options for
position. This can either be an X, Y, Width and Height, or an aspect ratio.</P>

<div id="configoption" name="prefixUseAspectRatio">
	<div id="prototype">(prefix)UseAspectRatio [bool]</div>
	<div id="defaultval">Default: false</div>
	<div id="description">
	</div>
</div>

<div id="configoption" name="prefixAspectRatio">
	<div id="prototype">(prefix)AspectRatio [float]</div>
	<div id="defaultval">Default: 1.0</div>
	<div id="description">
		If (prefix)UseAspectRatio is true, this element is positioned with an
		aspect ratio, which is its width divided by height. It will either be
		full-height or full-width, depending on the context in which it appears,
		and its aspect ratio will be as given in (prefix)AspectRatio.
	</div>
</div>

<div id="configoption">
	<div id="prototype" name="prefixX">(prefix)X [coord]</div>
	<div id="defaultval">Default: 0</div>
	<div id="prototype" name="prefixY">(prefix)Y [coord]</div>
	<div id="defaultval">Default: 0</div>
	<div id="prototype" name="prefixWidth">(prefix)Width [coord]</div>
	<div id="defaultval">Default: -0</div>
	<div id="prototype" name="prefixHeight">(prefix)Height [coord]</div>
	<div id="defaultval">Default: -0</div>
</div>

<div id="configoption">
	<div id="prototype" name="prefixMinLength">(prefix)MinLength [int]</div>
	<div id="prototype" name="prefixPreferredLength">(prefix)PreferredLength [int]</div>
	<div id="defaultval">Default: 0, 0</div>
	<div id="description">
		Sets minimum and preffered lengths for this element, used to determine how
		much space is allocated for it in a flow element. Note that if width or
		height (depending on whether it's a horizontal or vertical flow) is greater
		than MinLength, that is used instead.
	</div>
</div>

<H2>Common Options</H2>
<a name="common"/>

<div id="configoption" name="prefixType">
	<div id="prototype">(prefix)Type</div>
	<div id="defaultval">Mandatory setting</div>
	<div id="description">
		The element's type. See below for a listing of allowed types.
	</div>
</div>

<div id="configoption">
	<div id="prototype" name="prefixOnButtonPress">(prefix)On(Button)Press [command]</div>
	<div id="prototype" name="prefixOnButtonRelease">(prefix)On(Button)Release [command]</div>
	<div id="prototype" name="prefixOnButtonClick">(prefix)On(Button)Click [command]</div>
	<div id="defaultval">Default: none</div>
	<div id="description">
		Button is one of "Left", "Middle", or "Right". OnPress commands run when
		the mouse is pressed, and OnRelease commands when it's released. OnPress
		and OnRelease commands run independently of (and in addition to) drag and
		drop. OnClick commands run when the button is released, but only if the
		same thing is under the mouse as when the click started, and no drag/drop
		has taken place. If the command given is a Screenbar bang command,
		'clicked' is a valid desk/task description.
	</div>
</div>

<div id="configoption" name="prefixDraggable">
	<div id="prototype">(prefix)Draggable [bool]</div>
	<div id="defaultval">Default: false</div>
	<div id="description">
		Whether this element can be picked up and dragged around. In general, it is
		best for draggable elements to be as close to the top of the hierarchy as
		possible; in particular, draggable elements should not be the child of
		branch elements, since if conditions change and the dragged element no
		longer exists, the drag will be cancelled (possibly as soon as it begins!).
	</div>
</div>

<div id="configoption" name="prefixDragPlaceholder">
	<div id="prototype">(prefix)DragPlaceholder [element]</div>
	<div id="defaultval">Default: (prefix)</div>
	<div id="description">
		When this element is picked up and dragged, this is the element which stays
		behind to fill its place.
	</div>
</div>

<div id="configoption" name="prefixHoverGroup">
	<div id="prototype">(prefix)HoverGroup [bool]</div>
	<div id="defaultval">Default: false</div>
	<div id="description">
		If set to true, hovering over this element causes all of its children to
		count as being hovered.
	</div>
</div>

<div id="configoption" name="prefixOnHover">
	<div id="prototype">(prefix)OnHover_(element) [command]</div>
	<div id="defaultval">Default: none</div>
	<div id="description">
		What happens when a dragged (element) is hovered over this element. If this
		is a Screenbar bang command, 'dragged' and 'hovered' are valid desk/task
		descriptions.
	</div>
</div>

<div id="configoption" name="prefixOnDrop">
	<div id="prototype">(prefix)OnDrop_(element) [command]</div>
	<div id="defaultval">Default: none</div>
	<div id="description">
		What happens when a dragged (element) is dropped on this element. If this
		is a Screenbar bang command, 'dragged' and 'hovered' are valid desk/task
		descriptions.
	</div>
</div>

<div id="configoption" name="prefixIsMinimizeTarget">
	<div id="prototype">(prefix)IsMinimizeTarget [command]</div>
	<div id="defaultval">Default: false</div>
	<div id="description">
		If this element corresponds to a task, it will be used as the target for
		Windows' minimize/restore animation.
	</div>
</div>

<div id="configoption" name="prefixToolTip">
	<div id="prototype">(prefix)ToolTip [element-name]</div>
	<div id="defaultval">Default: ""</div>
	<div id="description">
		If set, hovering the mouse cursor over this element will cause the named
		tooltip window to appear.
	</div>
</div>

<div id="navigation">
	<a href="windows.html">Previous Page</a>
	<a href="index.html">Index</a>
	<a href="branch.html">Next Page</a>
</div>

</body>
</html>
